Platform - Overview & Basics
In order to get access to the Ximilar APP platform, please register at https://app.ximilar.com. In the app pick "Computer Vision Platform".
This page describes the Ximilar APP platform API, a powerful solution for training custom image recognition models. The platform supports multiple model types including Image Classification, Image Regression, Image Tagging, Custom Object Detection, and Flows. These models leverage cutting-edge AI and Machine Learning architectures such as Convolutional Neural Networks (CNNs) and Vision Transformers to deliver exceptional recognition capabilities.
The platform provides an intuitive user interface that simplifies the entire workflow—from task setup and account management to image upload, model training, and result evaluation. Once trained, your model is automatically deployed as an API endpoint that can be seamlessly integrated into your applications.
Compared to Large Language Models (LLMs), these specialized computer vision models offer significant advantages in terms of speed and cost-efficiency. They can run efficiently on standard hardware, with some models even capable of deployment on edge devices for on-premise processing.
Terminology
A task is the starting point for your machine learning project. Each task has a set of labels. A task represents the abstract definition for training a recognition model. Each label can be assigned to multiple training images. Your tasks, data, and images are private and accessible only to you.
A model is the trained version of a task - essentially a neural network trained on your specific images. This makes it highly accurate at recognizing new images. Each model has an accuracy metric measured at the end of training. Models are private to their owner. Each time you retrain a model, a new version is created with an incremented version number. You can select which model version to deploy in production.
Tasks can be of different types:
Image ClassificationTasks (further divided into):Tagging('multi_label'): Assigns multiple labels to an imageCategorization('multi_class'): Assigns a single category to an imageRegression('regression'): Predicts a numerical value
DetectionTasks: Identifies and locates objects within imagesSimilarityTasks: Determines how similar images are to each other
Note that a Tagging task automatically creates one Negative Label, and a Regression task can have only one label (of type value).
A Label represents a feature you want to recognize in your images. Each task has one or several labels. For Image Classification tasks, labels have specific types: category (for Categorization tasks), tag (for Tagging tasks), or value (for Regression tasks). You must upload training images to the platform and assign labels or create objects on these images.
A Workspace is where all your images, labels, and tasks are stored. By default, each user owns at least one workspace. You can share your workspace and grant access to other users.
Multiple tasks of different types can be combined and called together via the Flows service.
For example, if you want to recognize apples from bananas in images, you can create a Categorization Task with two Labels - Apple and Banana. You need to upload at least 20 images for the Apple label and another 20 images for the Banana label. After that, you can train the task, which may take several minutes or hours. The output of this training is a Model, which is deployed as an API. You can then make simple REST requests with images to classify them as either Apple or Banana.
Task Types
The Computer Vision Platform (Ximilar APP) allows you to train a several types of task:
Classification
This task type is ideal for categorizing images into predefined classes. It's particularly well-suited for high-quality images where you need to assign a single category to each image.
Endpoint: https://api.ximilar.com/recognition/v2/classify/
Best for: building simple model for categorizing image
Examples:
- Recognizing Cats vs Dogs on images.
- Recognizing Bedroom vs Kitchen vs Bathroom vs Living room.
- Recognizing Color of Clothing like Red vs Green vs Blue ...
Tagging
Tagging allows you to assign multiple labels to a single image. This is useful when an image contains multiple features or attributes that need to be identified simultaneously. In general a complex tagging model can be replaced by several simpler Classification models connected via Flows.
Endpoint: https://api.ximilar.com/recognition/v2/classify/
Best for: predicting several tags on image
Examples:
- Great for building Tagging system for Clothing that will predict Red, Green, Blue, Maxi, Midi, Mini, Long Sleeves, Short Sleeves, No Sleeves.
- If you want to assign features to Real Estate Images as Indoor, Outdoor, Kitchen, Wooden, Table, Chair, ...
- If you want to recognize Cat Vs Not-A-Cat (this is possible also in Categorization, here your Not-A-Cat label is represented by negative label).
Regression
Regression tasks are used when you need to predict continuous numerical values from images rather than discrete categories. This could be useful for predicting measurements, scores, or other numerical attributes.
Endpoint: https://api.ximilar.com/recognition/v2/classify/
Best for: predicting continous numerical values
Examples:
- If you want to build model that rates images like real estate photos from range (0-X).
- If you want to predict quality value / or damage of some product.
- If you want to build model that predicts aesthetics rating of stock photos.
Custom Similarity
This task type allows you to train models that can determine how similar images are to each other. It's useful for finding visually similar items, creating image search systems, or grouping similar images together.
Endpoint: https://api.ximilar.com/similarity/training/v2/descriptor
Best for: visual search system's that requires embedding models.
Examples:
- If you want to build a visual search for collectibles (cards, coins, stamps, comics, ...).
- If you want to build a visual search for fashion.
Object Detection
Object detection tasks identify and locate specific objects within images. This is useful when you need to know not just what objects are in an image, but also where they are located (typically with bounding boxes).
Endpoint: https://api.ximilar.com/detection/v2/detect
Best for: finding items and their location on images.
Examples:
- If you want to detect fashion items on images and find their location.
- If you want to detect home decor and furniture items on images.
- If you want to detect cars on CCTV cameras.
Useful endpoints
Here is the list of a basic endpoints that can be useful for you for getting details about your user, credits consumption, reports and more:
https://api.ximilar.com/account/v2/details/
https://api.ximilar.com/account/v2/reports/
https://api.ximilar.com/account/v2/workspace/
https://api.ximilar.com/account/v2/resource/
Get User Details
This endpoint returns detailed information about the authenticated user, including personal information, usage statistics, and credit information.
Required attributes
- Name
Authorization- Type
- string
- Description
API token for authentication.
Returns
HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed. Body of the response is a JSON object with the following fields:
- Name
id- Type
- string
- Description
Unique identifier of the user.
- Name
email- Type
- string
- Description
User's email address.
- Name
first_name- Type
- string
- Description
User's first name.
- Name
last_name- Type
- string
- Description
User's last name.
- Name
stats- Type
- object
- Description
Object containing usage statistics with the following fields:
- Name
credits_counter- Type
- integer
- Description
Current number of credits available to the user.
- Name
credits_limit- Type
- integer
- Description
Maximum number of credits the user can have.
- Name
default_workspace- Type
- string
- Description
ID of the user's default workspace.
Request
curl --location 'https://api.ximilar.com/account/v2/details/' \
--header 'Authorization: Token __API_TOKEN__'
Response
{
"id": "d7c949e2-c856-43b1-a8d4-f698d167cef7",
"email": "youremail@email.com",
"first_name": "Lorem",
"last_name": "Ipsum",
"stats": {
"recognition_task": 146,
"detection_task": 19,
"similarity_task": 13,
"collection": 11,
"flow": 24
},
"credits_counter": 128183952,
"credits_limit": 2147483647,
"default_workspace": "16502315-ef71-4424-9239-697458fe8e37"
}
Get User Statistics
This endpoint returns detailed statistics about the user's API usage, including request types and sub-resources. The data can be filtered by service, time granularity, and time period.
Required attributes
- Name
Authorization- Type
- string
- Description
API token for authentication.
- Name
type- Type
- string
- Description
Type of statistics to retrieve. Can be:
request_types- Statistics about different types of API requests (must be used with services parameter)sub_resources- Statistics about sub-resources (no services parameter should be specified)
Optional attributes
- Name
services- Type
- string
- Description
Slug of the service to filter statistics by. If you're not sure about the service slug, contact tech@ximilar.com.
- Name
granularity- Type
- string
- Description
Time granularity for the statistics. Can be:
hour- Hourly statisticsday- Daily statisticsweek- Weekly statisticsmonth- Monthly statistics
- Name
period_start- Type
- string
- Description
Start date and time for the statistics period in ISO 8601 format (e.g., "2025-03-01T00:00:00.000Z").
- Name
period_end- Type
- string
- Description
End date and time for the statistics period in ISO 8601 format. If not specified, the current date and time is used.
Returns
HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed. Body of the response is a JSON object containing statistics data based on the requested parameters.
Request
curl --location 'https://api.ximilar.com/account/v2/reports/?type=request_types&services=card-grader&granularity=month&period_start=2025-03-01T00:00:00.000Z' \
--header 'Authorization: Token __API_TOKEN__'
Response
{
"period_start": "2025-03-01T00:00:00Z",
"period_end": "2025-04-23T09:02:27.652110Z",
"granularity": "month",
"x": [
"2025-03-01T00:00:00Z",
"2025-04-01T00:00:00Z"
],
"total": {
"credits": 44950.0,
"records": 527
},
"series": [
{
"id": "condition",
"name": "Asess card condition",
"credits": [
2700.0,
2000.0
],
"requests": [
54,
40
]
},
{
"id": "grade-centering",
"name": "Centering of card",
"credits": [
2050.0,
1000.0
],
"requests": [
41,
20
]
},
{
"id": "grade-card",
"name": "Grade a card",
"credits": [
13400.0,
23800.0
],
"requests": [
134,
238
]
}
]
}
Get workspaces
This endpoint returns a list of all workspaces that the authenticated user has access to. A workspace is where all your images, labels, and tasks are stored. By default, each user owns at least one workspace.
Required attributes
- Name
Authorization- Type
- string
- Description
API token for authentication.
Returns
HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed. Body of the response is a JSON array with workspace objects, each containing the following fields:
- Name
id- Type
- string
- Description
Unique identifier of the workspace.
- Name
name- Type
- string
- Description
Name of the workspace.
- Name
created- Type
- string
- Description
Creation timestamp in ISO 8601 format.
- Name
owner- Type
- string
- Description
User ID of the workspace owner.
- Name
meta_data- Type
- object
- Description
Additional metadata for the workspace, can be null.
- Name
is_default- Type
- boolean
- Description
Whether this is the default workspace for the user.
- Name
blur_images- Type
- boolean
- Description
Whether images in this workspace should be blurred.
Request
curl --location 'https://api.ximilar.com/account/v2/workspace' \
--header 'Authorization: Token __API_TOKEN__'
Response
[
{
"id": "e5b26c2c-21b9-4fbb-ab75-a5966c3cba02",
"name": "Default",
"created": "2022-01-18T11:57:49.046245Z",
"owner": "4a5a6366-84c9-47b9-b302-8c32da13ced0",
"meta_data": null,
"is_default": true,
"blur_images": false
},
{
"id": "c9f55ec4-f0c4-4bd3-9ea6-9388754dadad",
"name": "Workspace X",
"created": "2023-11-03T12:24:31.769290Z",
"owner": "d7c949e2-c856-43b1-a8d4-f698d167cef7",
"meta_data": null,
"is_default": false,
"blur_images": false
}
]
Get User Resources
This endpoint returns a list of all services that the authenticated user has access to. This includes both standard services and custom services that have been created for the user.
Required attributes
- Name
Authorization- Type
- string
- Description
API token for authentication.
Returns
HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed. Body of the response is a JSON object with the following fields:
- Name
count- Type
- integer
- Description
Total number of resources available to the user.
- Name
next- Type
- string
- Description
URL for the next page of results, or null if there are no more pages.
- Name
previous- Type
- string
- Description
URL for the previous page of results, or null if this is the first page.
- Name
results- Type
- array
- Description
Array of resource objects, each containing:
Request
curl --location 'https://api.ximilar.com/account/v2/resource/' \
--header 'Authorization: Token __API_TOKEN__'
Response
{
"count": 4,
"next": null,
"previous": null,
"results": [
{
"id": 16472,
"service": {
"id": 33,
"name": "AI Recognition of Collectibles",
"slug": "collectibles-recognition"
},
"created": "2024-06-11T19:20:22.755727Z"
},
{
"id": 16574,
"service": {
"id": 40,
"name": "OCR",
"slug": "ocr"
},
"created": "2024-06-24T20:04:45.718000Z"
},
{
"id": 16954,
"service": {
"id": 0,
"name": "Image Classification & Regression",
"slug": "custom-recognition"
},
"created": "2024-08-06T08:16:13.267323Z"
},
{
"id": 17219,
"service": {
"id": 44,
"name": "Fashion Search & Recommendation",
"slug": "fashion-search"
},
"created": "2025-02-14T11:36:42.631717Z"
}
]
}